{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pyplot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pyplot` is a context based functional API offering meaningful defaults. It's a concise API and very similar to matplotlib's pyplot. Users new to `bqplot` should use `pyplot` as a starting point. Users create figure and mark objects using `pyplot` functions.\n",
    "\n",
    "Steps for building plots in `pyplot`:\n",
    "1. Create a figure object using plt.figure()\n",
    "* (Optional steps)\n",
    "    * Scales can be customized using `plt.scales` function\n",
    "    * Axes options can customized by passing a dict to `axes_options` argument in the marks' functions\n",
    "* Create marks using `pyplot` functions like `plot`, `bar`, `scatter` etc. (All the marks created will be automatically added to the figure object created in step 1)\n",
    "* Render the figure object using the following approaches:\n",
    "    * Using `plt.show` function which renders the figure in the current context along with toolbar for panzoom etc.\n",
    "    * Using display on the figure object created in step 1 (toolbar doesn't show up in this case)\n",
    "\n",
    "`pyplot` also offers many helper functions. A few are listed here:\n",
    "* plt.xlim: sets the domain bounds of the current 'x' scale\n",
    "* plt.ylim: sets the domain bounds of the current 'y' scale\n",
    "* plt.grids: shows/hides the axis grid lines\n",
    "* plt.xlabel: sets the X-Axis label\n",
    "* plt.ylabel: sets the Y-Axis label\n",
    "* plt.hline: draws a horizontal line at a specified level\n",
    "* plt.vline: draws a vertical line at a specified level\n",
    "\n",
    "Let's look at the same examples which were created in the [Object Model Notebook](Object Model.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import bqplot.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# first, let's create two vectors x and y to plot using a Lines mark\n",
    "import numpy as np\n",
    "x = np.linspace(-10, 10, 100)\n",
    "y = np.sin(x)\n",
    "\n",
    "# 1. Create the figure object\n",
    "fig = plt.figure(title='Simple Line Chart')\n",
    "\n",
    "# 2. By default axes are created with basic defaults. If you want to customize the axes create \n",
    "# a dict and pass it to `axxes_options` argument in the marks\n",
    "axes_opts = {'x': {'label': 'X'}, \n",
    "             'y': {'label': 'Y'}}\n",
    "\n",
    "# 3. Create a Lines mark by calling plt.plot function\n",
    "line = plt.plot(x=x, y=y, axes_options=axes_opts) # note that custom axes options are passed here\n",
    "\n",
    "# 4. Render the figure using plt.show()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For creating other marks (like scatter, pie, bars, etc.), only step 2 needs to be changed. Lets look a simple example to create a bar chart:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# first, let's create two vectors x and y to plot a bar chart\n",
    "x = list('ABCDE')\n",
    "y = np.random.rand(5)\n",
    "\n",
    "# 1. Create the figure object\n",
    "fig = plt.figure(title='Simple Bar Chart')\n",
    "\n",
    "# 2. Customize the axes options\n",
    "axes_opts = {'x': {'label': 'X', 'grid_lines': 'none'},\n",
    "             'y': {'label': 'Y', 'tick_format': '.0%'}}\n",
    "\n",
    "# 3. Create a Bars mark by calling plt.bar function\n",
    "bar = plt.bar(x=x, y=y, padding=.2, axes_options=axes_opts)\n",
    "\n",
    "# 4. directly display the figure object created in step 1 (note that the toolbar no longer shows up)\n",
    "fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mutiple marks can be rendered in a figure. It's as easy as creating marks one after another. They'll all be added to the same figure!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# first, let's create two vectors x and y\n",
    "import numpy as np\n",
    "x = np.linspace(-10, 10, 25)\n",
    "y = 3 * x + 5\n",
    "y_noise = y + 10 * np.random.randn(25) # add some random noise to y\n",
    "\n",
    "# 1. Create the figure object\n",
    "fig = plt.figure(title='Scatter and Line')\n",
    "\n",
    "# 3. Create line and scatter marks\n",
    "# additional attributes (stroke_width, colors etc.) can be passed as attributes to the mark objects as needed\n",
    "line = plt.plot(x=x, y=y, colors=['green'], stroke_width=3)\n",
    "scatter = plt.scatter(x=x, y=y_noise, colors=['red'], stroke='black')\n",
    "\n",
    "# setting x and y axis labels using pyplot functions. Note that these functions \n",
    "# should be called only after creating the marks\n",
    "plt.xlabel('X')\n",
    "plt.ylabel('Y')\n",
    "\n",
    "# 4. render the figure\n",
    "fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pyplot` is a simpler and an intuitive API. It's available for all the marks except MarketMap. It should be used in almost all the cases by default since it offers a less verbose API compared to the Object Model. Please refer to the mark [examples](../Marks/Pyplot) using `pyplot` and also this [pyplot example](../Basic Plotting/Pyplot.ipynb) notebook"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
